Close the plugin's task-queue vocabulary drift, then gate it (vikunja#558, #543) - #10

Build agent-workflow-interop-2026-08 Phase 2. Closes vikunja#558, folding in #543 — same four files, same defect class.

The drift

task-queue-mcp made routing-failed a first-class non-terminal status and counts it in active on GET /queue/summary. This plugin carried four partial hand-written copies of a vocabulary it does not own, and none of them were updated:

The status most in need of an operator was the one that sorted last and looked least urgent. Nothing detected it: a missing key in a Record<string, …> is not a type error, and a switch with a default has no missing case.

What changed

routing-failed is a known status everywhere. Sorts above in-progress — first in its group — renders error rather than muted, is offered by the status filter, and is a valid destination in the operator status-change control. Setting it by hand is not a dead end: the dispatcher's process_routing_failed pass picks up any such task whose retry window has passed, and is_eligible returns true when next_retry_at is absent — so it reads as "re-route now, skipping re-approval", which is a thing an operator wants.

A routing-failed task explains itself. The detail view gains a banner naming what the dispatcher is doing, retries used, next attempt, and that the end of the budget is a dead letter.

A queued manual-then-auto survives the Start button (#543). toWorkflowMode collapsed it to semi-auto, which re-pins every task the session spawns back to semi-auto — the exact failure vikunja#533 added the mode to fix (four security→steward return tasks sat unactioned for over a week). review on such a task now passes manual-then-auto through; run-steward.sh already accepts it and does the downgrade. An explicit auto Start still overrides, and the launch note says which it did. This was a live behavioural bug, not just a missing badge.

src/vocabulary.ts now holds one copy of the vocabulary plus the UI maps keyed by it. STATUS_ORDER and STATUS_COLOR are Record<Status, …>, so adding a status without a sort position and a colour is a tsc error. That is the half the old code lacked — Record<string, number> accepts anything and covers nothing.

Also: a Mode filter and a mode badge (rows badge auto and manual-then-auto, stay quiet about semi-auto, which is 98% of the queue); a task with no recorded workflow_mode renders as unknown rather than as the queue's default, because older records predate the field and inventing a value the queue never wrote is how this class of bug starts.

The gate

npm run gate:vocabulary fetches task-queue-mcp's main and asserts the sets match. Ported from task-dispatcher/tests/test_task_queue_vocabulary.py (vikunja#324) keeping both properties that make that one work:

• No skip-on-no-network path. It exits non-zero if it cannot read the upstream. A check that quietly passes when it could not reach its source of truth is indistinguishable from one that verified something, and that shape is how #324 stayed open for months. It likewise exits non-zero if it parses zero set literals rather than reporting a vacuous pass over an empty comparison.
• Tracks main, not a pin. A vocabulary change merged upstream turns this repo red on the next push. That is the alarm, not a malfunction. TASK_QUEUE_MCP_REF exists only for a paired pre-merge change from a shell; CI does not set it, and the ref is charset-constrained so it cannot traverse to another repo's path on raw.githubusercontent.com.

It is its own CI step, after npm test. A red vocabulary means "go edit src/vocabulary.ts" — a different instruction from any unit failure — and folded into one command either could hide the other.

Nothing fetched is executed and no Python runs: a narrow tokenizer (src/gates/python-sets.ts, split out so it is testable) accepts a brace-delimited list of plain string literals and refuses everything else, including the two upstream constructs that must not parse as sets — the derived NON_TERMINAL_STATUSES = VALID_STATUSES - TERMINAL_STATUSES and the annotated VALID_TRANSITIONS: dict[...].

Proof it fires

A gate nobody has seen fail is not yet a gate. All four outcomes verified before this was opened:

The new assertions were each verified red against the defect they cover, by mutating the fix back: routing-failed sorting last (2 fail), rendering muted (1 fail), omitted from NON_TERMINAL_STATUSES (2 fail), toWorkflowMode flattening manual-then-auto (2 fail), the parser accepting a derived set (1 fail), and the parser matching an annotated assignment (1 fail). Baseline green in every case after restore.

Also

Relative imports now use .ts, not .js. node --test runs the sources directly under type stripping and does not rewrite a .js specifier to the .ts file beside it — the panels all used .js and were simply never imported by a test; the first one that needed to be, was not.

Verification

• npm run build (tsc + esbuild) clean
• npm test — 110 pass, 0 fail (was 85)
• npm run gate:vocabulary — in sync

The UI half (sort position, colour, banner, filter, badge) needs eyes in CloudCLI after ./deploy.sh && pm2 restart cloudcli — pm2 is sysadmin's, so that goes out as a deploy task.

🤖 Generated with Claude Code